ObiWan is dedicated to beta testers and freeware and shareware authors.
“ObiWan is a must-have”
- Australian&New Zealand MacUser, Pg 88, Nov 1993.
What ObiWan Does
ObiWan is a general help system. You can create several databses and ObiWan will let you rapidly find information from them. It displays the information by popping up a floating window so the information can be displayed at any time in any program. Portions of the information can then be sent to the front window as if you had typed it. The main use of all this is to access the programming database, which includes the procedures, traps, global variables and errors available up to most of System 7.5 (including GX, OCE and OT) and the Universal Interfaces. Also included is a word list and Perl help database. ObiWan requires System 7.1 (for the Text Services Manager).
Previous versions were free, but the amount of time required to keep the database up to date with new system releases requires some justification, so ObiWan is now $10 shareware.
Features
The Force file includes all the System 7 information, including Universal Interfaces.
The Force database is quite up to date, including lots of the new managers.
Any number of databases may exist, only one of which is active at any time.
First word searches are instantaneous, general searches are very quick.
Databases are plain text files and can be edited at any time they are not active.
Databases are reindexed automatically when the file size changes.
Database file size is unlimited.
Databases can have any number of entries.
There is absolutely no dependency on MacTCP at all.
Caveats:
Clicks occasionally get lost. Anyone from Apple care to comment why sometimes jGNEFilter isn’t called? This can be fixed by installing Matt Slot's TSM Fix extension.
Keys typed in to ObiWan also go into a DA window if a DA is front-most.
The Finder doesn't like having keys dumped at it for some reason.
Using ObiWan
Make an alias to ObiWan and drop it in the Startup Items folder in your System folder. Launch it.
ObiWan silently waits in the background for you to press cmd-` at which time it will pop up a window and let you find entries in the database. Type cmd-` (hold down the cloverleaf key and press the back-quote key (`)). Read the help there, or type "a" and a return to redisplay the help text. Click on the arrows to move thru the database. Double-click on words to find their entry.
The buttons and their respective keys are, from left to right:
Lookup <return>
Search Anywhere <shift-return>
Move Backwards <cmd-,>
Move Forewards <cmd-.>
Jump Back <cmd-[>
Type Word <cmd-enter>
Type Line <cmd-option-enter>
Type Procedure <cmd-shift-enter>
Type Entire Entry <cmd-option-shift-enter>
Play sound at launch (toggles the preference)
Play sound at invokation (toggles the preference)
About
Change Database or Parse Procedure <option-return>
NOTE: The startup and invokation sounds have been removed from the Metrowerks distributed version to avoid any copyright problems.
The Force database is partially produced by parsing the PInterfacesHelp file which I have license from Apple. Thanks to Rick Fleischman, Barbara Napier, and Apple Computer, Inc. for waiving the fee to allow the Force file to be distributed. The Force file contains all the System 6 and 7 procedures, constants, errors, and global variables. You can find these by opening ObiWan (cmd-`), typing in the start of the name (eg HOpen) and pressing return. You can then insert the routine into THINK Pascal or C or MPW by clicking the third insert button (the one that looks like a procedure) (or by typing cmd-shift-enter). Note that there is a Pascal bias in this database because I am biased towards Pascal, but there is no reason some bright spark couldn’t produce a C equivalent database. You can also look up traps, errors, globals by searching for:
trapA000 - four digit hex number, starting with A
err-108 - decimal number, starting with a minus for OSErrs
err25 - decimal number, positive for system errors.
global910 - three digit hex number for global variables. (QuickDraw globals are not included)
You can change to using the C Parse Procedure by typing “C<option-return>”
The Force database is not special in any way (except that it contains the programming information for System 7). You can create other databases and switch between them by typing the name <name> and clicking the change button (furthest to the right) (or typing <option-return>). Other databases that are might be available include: a word dictionary (included); a thesaurus (both based on Roget's thesaurus from the Gutenburg project); a perl database (included); a Newton database (out of date now) and possibly a unix database (similar to Force, but for unix commands).
Using Master Yoda
Launch Master Yoda.
Click the Select button to select a database, then you can get Stats on the database, sort it, add another (sorted!) database, index the database (but that is done automatically for you anyway), or change the word set characters for the database.
Database Format
An ObiWan database is just a TEXT file with a strict format, plus some resources in the resource fork, including the index (which is recalculated if the file size changes) the word character set. The format of the text file is (by example):
=|
indexword data
general stuff, up to 10 lines, each up to 80 characters, ending with a|
nextindexword more data
more stuff|
verynextindexedword more and more data
finally ending with|
=|
The file should be sorted by the indexword (Master Yoda’s sort sorts by the entire entry so if you want related parts to stay in the same order when the database is sorted, they must be ordered in that way). The sort order is straight ASCII, case insensitive. Yes, I can hear you screaming “No, no, use the language independent sort order that the system defines”, (and yes, I do think that comma should go outside the quote mark irrespective of what the English teachers would have you believe :-) but I wish to be able to distribute a database file that works on all machines without having to be resorted.
Let’s see if I can define a BNF for the database format:
character ::= chr(9) | chr(32)..chr(126) | chr(128)..chr(255)
lines MUST be at most 80 characters, and should fit into the window in Geneva 9.
entries MUST be at most 10 lines.
There is no limit to the file size or number of entries (well, ok, the file size is limited by the file system, but thats not my fault, and the number of entries is obviously limited by the size of the file...)
Note: The file absolutely must start and end with =|<cr>. No trailing blank lines.
How It Works
ObiWan uses the Text Services manager to display the floating window (and thus requires System 7.1), and patches into the jGNEFilter list to receive events.
Later on, it watches keypresses and if a match for the popup key appears it opens the display window and accepts key strokes. When you hit return it takes the first eight letters of the word (padding with zeros), and scans thru an index to find where in the database that word comes, then it positions itself in the database and scans the entries until it finds a matching one and displays that. The “anywhere” search is done using Boyer-Moore search routine - this is one of the most elegant and simple routines I’ve ever seen, if you ever do any searching code, check this out, it is hardly any more complicated than a brute force search, but takes time *inversely* proportional to the length of the search string!
Entering characters into the front application is done by simply returning key down events (with key codes) in response to null events. Word still gets confused (because it only calls WNE if there is an event waiting), but thats to be expected.
Limitations
ObiWan & Master Yoda require System 7.1 or later.
There is a problem with clicks in ObiWan’s display area sometimes being ignored. This happens because the click is sometimes stolen before it gets to the jGNEFilter. You can fix this by installing Matt Slot's TSM Fix (included).
There is also a problem that key presses go into DA windows instead of ObiWan. I don’t really think this is a major problem, but perhaps others disagree.
If you quit ObiWan (using ProcessWatcher for example), the icon remains greyed out in the Finder. This is a bug in the Finder.
Small Print
This program is Shareware, which means if you use it, you should send me US$10.
Site Licensing:
World-wide license: US$2000
Universities or companies site license: US$500
Curtin University and the University of Western Australia are exempt.
Single-user license: US$10.
Use the Register provided to fill out the registration form and send (Email, Snail-Mail or FAX) it to my US distributer, Kagi Shareware.
If you purchase a site license, contact me for information on how to make this program automatically set the “I Paid” flag in the Preferences dialog.
You may distribute this program any way you wish as long as you don't charge for it (except for reasonable download costs). I don’t guarantee any support, but I always answer my Email. If I don’t answer Email its because your message didn’t get to me, or my reply bounced, so try again and include a valid Internet address if you can.
You MAY NOT DISTRIBUTE this program on any disk costing more than $5 without my explicit permission. You MAY NOT DISTRIBUTE this program on any CD without my explicit permission.
Warranty
This program should do what I’ve described in this document. If it doesn’t, you can simply stop using it. If you pay me, and within a year find that it doesn’t do what I describe here, then you can notify me and I will refund your money and cancel your license.
Fine Print
Peter Lewis hereby disclaims all warranties relating to this software, whether express or implied, including without limitation any implied warranties of merchantability or fitness for a particular purpose. Peter Lewis will not be liable for any special, incidental, consequential, indirect or similar damages due to loss of data or any other reason, even if Peter Lewis or an agent of his has been advised of the possibility of such damages. In no event shall Peter Lewis be liable for any damages, regardless of the form of the claim. The person using the software bears all risk as to the quality and performance of the software.
US Governement:
Government End Users: If you are acquiring the Software and fonts
on behalf of any unit or agency of the United States Government, the
following provisions apply. The Government agrees:
(i) if the Software and fonts are supplied to the Department of
Defense (DoD), the Software and fonts are classified as "Commercial
Computer Software" and the Government is acquiring only "restricted rights"
in the Software, its documentation and fonts as that term is defined in
Clause 252.227-7013(c)(1) of the DFARS; and
(ii) if the Software and fonts are supplied to any unit or agency
of the United States Government other than DoD, the Government's rights in
the Software, its documentation and fonts will be as defined in Clause
52.227-19(c)(2) of the FAR or, in the case of NASA, in Clause
18-52.227-86(d) of the NASA Supplement to the FAR.
Acknowledgements
This program, like many of my others, would never have gotten here without the help of my friends. Thanks!
Thanks to Jager, Quinn, and Rhys for their ideas and suggestions for ObiWan in the initial design phase. Thanks you J&Q for the initial parsing of the PInterfacesHelp file and the colour icons. Thanks also to the UCC, Curtin, Todd (have fun at Momentum!), Steve, c.s.m.p, plaza, ftp.apple.com, Stephen, and anyone who uses ObiWan! Thanks to Greg and the guys at Metrowerks for including ObiWan and giving me a license to their wonderful compiler. ObiWan is written in Metrowerks Pascal. Special thanks go to those brave souls who risked life and Mac beta testing an unknown program. Thanks to Matt Slot for the TSM Fix extension.
